…y processors (#3497)

RFC-18 flex-algo · PR 1 of 5 · see `rfcs/rfc-0018-flex-algo.md`
Series: #3497 · #3512 · #3513 · #3514 · #3515

## Summary of Changes
- Adds `TopologyInfo` onchain account (RFC-18 flex-algo) with
`admin_group_bit`, `flex_algo_number`, and `TopologyConstraint`; creates
`AdminGroupBits` resource extension singleton for bit allocation
- Adds four new foundation-only instructions (107–110):
`CreateTopology`, `DeleteTopology`, `ClearTopology`, `BackfillTopology`
- Extends `Link` with `link_topologies` (Vec<Pubkey>) and `link_flags`
(LINK_FLAG_UNICAST_DRAINED); extends `Tenant` with `include_topologies`;
adds `flex_algo_node_segments` to Interface V2
- `CreateLink` now requires the unicast-default topology account and
auto-tags the link into it
- `UpdateLink` gains foundation-gated `link_topologies` update and
contributor-gated `unicast_drained` flag

## Diff Breakdown
| Category    | Files | Lines (+/-)   | Net   |
|-------------|-------|---------------|-------|
| Core logic  |    22 | +1,306 / -38  | +1,268|
| Scaffolding |    49 | +133 / -3     |  +130 |
| Tests       |    27 | +4,592 / -74  | +4,518|

The scaffolding is mechanical struct field additions (`link_topologies:
vec![]`, `include_topologies: vec![]`, `flex_algo_node_segments:
vec![]`) across CLI, SDK, activator, and client to keep the workspace
compiling. Core logic is concentrated in the new topology processors,
state types, and link/activate updates.

<details>
<summary>Key files (click to expand)</summary>

-
`smartcontract/programs/doublezero-serviceability/src/state/interface.rs`
— updates Interface V2 (discriminant 1) to include
`flex_algo_node_segments: Vec<FlexAlgoNodeSegment>`; V1 accounts
(pre-CYOA format) are left as-is; pre-RFC-18 V2 accounts on mainnet are
upgraded in-place by `MigrateDeviceInterfaces` before this
deserialization path is used
-
`smartcontract/programs/doublezero-serviceability/src/state/topology.rs`
— new `TopologyInfo` account: `admin_group_bit` (u8), `flex_algo_number`
(128+bit), `TopologyConstraint` (IncludeAny/Exclude)
-
`smartcontract/programs/doublezero-serviceability/src/processors/topology/`
— five new processors: create (allocates AdminGroupBit, validates
IdRange 1–127), delete, clear (removes topology from all links),
backfill (allocates FlexAlgoNodeSegment on all device interfaces)
-
`smartcontract/programs/doublezero-serviceability/src/processors/link/update.rs`
— adds foundation-gated `link_topologies` update (validates each
topology account onchain) and contributor-gated `unicast_drained` flag
(LINK_FLAG_UNICAST_DRAINED bit 0)
-
`smartcontract/programs/doublezero-serviceability/src/processors/link/activate.rs`
— requires `unicast_default_topology_account` as a mandatory account;
auto-tags new link into the unicast-default topology on activation
-
`smartcontract/programs/doublezero-serviceability/src/processors/globalconfig/set.rs`
— creates `AdminGroupBits` ResourceExtension PDA on global config
initialization
- `smartcontract/programs/doublezero-serviceability/src/state/link.rs` —
adds `link_topologies: Vec<Pubkey>`, `link_flags: u64`, and
`LINK_FLAG_UNICAST_DRAINED = 0x01`
- `smartcontract/programs/doublezero-serviceability/src/instructions.rs`
— registers four new instruction variants (CreateTopology=107,
DeleteTopology=108, ClearTopology=109, BackfillTopology=110)

</details>

## Testing Verification
- `make rust-lint` and `make rust-test` pass clean on this branch
- `topology_test.rs` (~2,400 lines) covers all four topology processors:
create/delete/clear/backfill, including error paths (duplicate names,
out-of-range bits, unauthorized signers, invalid topology accounts),
segment allocation, and multi-topology backfill
- Existing `link_wan_test.rs`, `tenant_test.rs`, and telemetry tests
updated to account for the new mandatory
`unicast_default_topology_account` in `ActivateLink`

---------

Co-authored-by: Greg Mitchell <greg@malbeclabs.com>

RFC-18 flex-algo · PR 2 of 5 · see `rfcs/rfc-0018-flex-algo.md`
Series: #3497 · #3512 · #3513 · #3514 · #3515

## Summary of Changes
- Adds five `doublezero link topology` subcommands: `create`, `delete`, `clear`, `backfill`, `list`
- `topology create` allocates the admin-group bit and flex-algo number onchain, then automatically backfills `FlexAlgoNodeSegment` entries on all activated Vpnv4 loopback interfaces
- `topology backfill` and `topology clear` batch at 16 accounts per transaction to stay within Solana's 32-account limit; zero accounts → zero transactions sent
- `topology list` displays each topology's name, admin-group bit, flex-algo number, BGP color community, constraint, and count of tagged links
- Backs each subcommand with a Rust SDK command in `doublezero_sdk::commands::topology`
- Simplifies the `BackfillTopology` onchain processor: removes the two-pass SR ID pre-marking loop; keeping the `SegmentRoutingIds` resource in sync with off-chain allocations is the activator's responsibility

## Diff Breakdown
| Category    | Files | Lines (+/-)    | Net    |
|-------------|-------|----------------|--------|
| Core logic  |    11 | +1,572 / -32   | +1,540 |
| Scaffolding |     8 |   +91 /  -6    |   +85  |
| Tests       |     1 |   +25 / -16    |    +9  |

Core logic includes inline unit tests in the SDK command files.

<details>
<summary>Key files (click to expand)</summary>

- `smartcontract/sdk/rs/src/commands/topology/create.rs` — creates topology, then enumerates devices and calls `BackfillTopologyCommand` for those with Vpnv4 loopbacks; returns `CreateTopologyResult { signature, topology_pda, backfill_signatures }`
- `smartcontract/sdk/rs/src/commands/topology/backfill.rs` — batches devices in chunks of 16; returns `Vec<Signature>`; empty device list sends no transactions
- `smartcontract/sdk/rs/src/commands/topology/clear.rs` — batches links in chunks of 16; returns `Vec<Signature>`; empty link list sends no transactions
- `smartcontract/sdk/rs/src/commands/topology/list.rs` — fetches all `TopologyInfo` accounts and cross-references link accounts to compute per-topology link counts
- `smartcontract/cli/src/topology/create.rs` — CLI wrapper; prints PDA and backfill transaction count
- `smartcontract/cli/src/topology/list.rs` — tabular display of name, bit, algo number, BGP color, constraint, link count
- `smartcontract/programs/doublezero-serviceability/src/processors/topology/backfill.rs` — removes two-pass SR ID pre-marking; single-pass allocation only

</details>

## Testing Verification
- `cargo test -p doublezero_sdk -p doublezero_cli` passes
- `cargo clippy -- -D warnings` clean
- `make rust-fmt` applied

RFC-18 flex-algo · PR 4 of 5 · see
[`rfcs/rfc-0018-flex-algo.md`](../tree/main/rfcs/rfc-0018-flex-algo.md)
Depends on: #3512 (PR 2), #3513 (PR 3)
Series: #3497 · #3512 · #3513 · #3514 · #3515

## Summary of Changes

- Python SDK: deserialize `TopologyConstraint`, `TopologyInfo`, and
`FlexAlgoNodeSegment`; read `flex_algo_node_segments` from the RFC-18
`InterfaceV3` account format
- TypeScript SDK: deserialize `FlexAlgoNodeSegment` from `InterfaceV3`
account format; guard the segments loop against pre-RFC-18 mainnet
accounts where the segment count reads garbage bytes
- SDK fixtures: regenerate device, link, tenant, and user fixtures to
include the new `InterfaceV3` fields
- TypeScript RPC client: remove the `AbortController` timeout wrapper
around `fetch` (was surfacing as spurious `TimeoutError` on slow
`getProgramData` responses); bump the compat test's request timeout to
120s
- `tryReadString` in `borsh-incremental`: check remaining buffer length
before reading to avoid out-of-bounds reads
- CHANGELOG / e2e compatibility test: document the mandatory CLI upgrade
boundary for RFC-18 `InterfaceV3` (devices written by the new program
cannot be deserialized by pre-RFC-18 CLI versions)

Note: activator changes that were originally planned for this PR have
been dropped — the doublezero activator is deprecated.

## Diff Breakdown

| Category   | Files | Lines (+/-) |
|------------|-------|-------------|
| Python SDK |     1 | +61 / -1    |
| TS SDK     |     3 | +27 / -3    |
| Fixtures   |     5 | +4 / -1 + bin |
| Docs/e2e   |     2 | +2 / -2     |

## Testing Verification

- Python SDK: `uv run pytest` passes under `sdk/serviceability/python/`,
including fixture deserialization
- TypeScript SDK: `bun test` passes under
`sdk/serviceability/typescript/`, including compat fixture
deserialization with the new `InterfaceV3` fields
- `cargo check --workspace` clean

…troller support

RFC-18 flex-algo · PR 5 of 5 · see `rfcs/rfc-0018-flex-algo.md`
Depends on: #3497 (PR 1) — does not require PRs 2–4; can merge after PR
1
Series: #3497 · #3512 · #3513 · #3514 · #3515

## Summary of Changes
- Adds `TopologyInfo` account type to the Go SDK (`state.go`,
`deserialize.go`, `client.go`), including `TopologyType`,
`TopologyConstraint`, `LinkFlagUnicastDrained`,
`LinkTopologies`/`LinkFlags` on `Link`, and `IncludeTopologies` on
`Tenant`
- Auto-loads `/etc/doublezero-controller/features.yaml` at startup if
present (silently skips if absent); when `flex_algo.enabled: true`,
populates topology data into the state cache, resolves tenant color
communities via `resolveTenantColors`, and emits IS-IS flex-algo node
segment and link configuration into the Arista EOS template
- Template emits correct flex-algo definitions for both `include-any`
constraint (`administrative-group include any N exclude 0`) and
`exclude` constraint (`administrative-group exclude N,0`) topologies;
gated per-link via `link_tagging.exclude` and per-tenant via
`community_stamping`
- Updates `e2e/compatibility_test.go` to set the mandatory upgrade
boundary for RFC-18 interface/link operations to `before: "0.18.0"`

## Diff Breakdown
| Category    | Files | Lines (+/-)  | Net   |
|-------------|-------|--------------|-------|
| Core logic  |     6 | +368 / -6    | +362  |
| Scaffolding |     2 | +22 / -0     |  +22  |
| Tests       |     4 | +482 / -2    | +480  |
| Fixtures    |     2 | +415 / -0    | +415  |
| Docs        |     1 | +4 / -0      |   +4  |

Most of the weight is tests and fixtures; core logic is the controller
cache/template and Go SDK deserialization.

> **Note on diff size:** The full diff vs `main` is large because this
branch is stacked on PR 1 (#3497), which has not yet merged. The table
above reflects only PR 5's contribution. After PR 1 merges and this
branch is rebased, the diff shrinks to the ~15 files shown here.

<details>
<summary>Key files (click to expand)</summary>

-
[`controlplane/controller/internal/controller/server.go`](https://github.com/malbeclabs/doublezero/pull/3515/files#diff-f5e715ed1377ac408a4ecde2c60cbcb98327512c7d1496114ef143cb27e7afaf)
— populates `Topologies` map in state cache; resolves `LinkTopologies`
pubkeys to topology names and `UnicastDrained` from `LinkFlags`;
computes `TenantTopologyColors`; `resolveTenantColors` falls back to
`unicast-default` when tenant has no explicit topology assignments
-
[`controlplane/controller/internal/controller/templates/tunnel.tmpl`](https://github.com/malbeclabs/doublezero/pull/3515/files#diff-d67a980326aca35fdabdd5445fbbab4716f1ae412af4540770d5a9ee116b04d9)
— IS-IS flex-algo node segment config, link admin-group tagging, BGP
`next-hop resolution ribs` and `set extcommunity` stamping, and full
rollback (`no` commands) when disabled; handles both `include-any` and
`exclude` constraint topologies
-
[`controlplane/controller/internal/controller/features_config.go`](https://github.com/malbeclabs/doublezero/pull/3515/files#diff-24f09aab331b4d309662e5ee6550fd38fa173676ae868db381d9af23cf645f1d)
— `FeaturesConfig` struct with `flex_algo.enabled`,
`link_tagging.exclude`, and `community_stamping` controls; auto-loaded
from `/etc/doublezero-controller/features.yaml`
-
[`controlplane/controller/internal/controller/models.go`](https://github.com/malbeclabs/doublezero/pull/3515/files#diff-bdc4e34592a7435dcde7dab78ffd735dcb9847447f0113bd9f3afc8d3d01f864)
— adds `LinkTopologies`, `UnicastDrained`, `FlexAlgoNodeSegments`,
`TenantTopologyColors` to controller model types; `TopologyModel` and
`FlexAlgoEnabled()` for template rendering
-
[`smartcontract/sdk/go/serviceability/state.go`](https://github.com/malbeclabs/doublezero/pull/3515/files#diff-057f627e5f2629b35f1976fba6eaa1b3c507c511b0f47d2f80a3a1d0c684c4a1)
— adds `TopologyType`, `TopologyConstraint`, `TopologyInfo`,
`LinkFlagUnicastDrained`; extends `Link` with
`LinkTopologies`/`LinkFlags` and `Tenant` with `IncludeTopologies`
-
[`smartcontract/sdk/go/serviceability/deserialize.go`](https://github.com/malbeclabs/doublezero/pull/3515/files#diff-b71f90b1b3e00de9bd820920e63f5615edb9b7d110c2b39f38895847509a7844)
— adds `DeserializeTopologyInfo`; extends `DeserializeLink` with
`LinkTopologies`/`LinkFlags` and `DeserializeTenant` with
`IncludeTopologies`

</details>

## Testing Verification
- `TestGetConfig_FlexAlgo` (new): render tests for flex-algo disabled,
enabled with both constraint types (`include-any` and `exclude`), and
link excluded from tagging — all pass
- `Test_resolveTenantColors` (new): 5 table-driven cases covering
fallback to `unicast-default`, missing topology, single/multiple known
pubkeys, and unknown pubkey — all pass
- `TestE2E_IBRL`, `TestE2E_IBRL_WithAllocatedAddr`, `TestE2E_Multicast`
— all pass; flex-algo config is suppressed in e2e (no `features.yaml`
present)
- `exclude` constraint flex-algo syntax validated on physical lab
switches (chi-dn-dzd5–dzd8)

---------

Co-authored-by: Greg Mitchell <greg@malbeclabs.com>